<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Symbols Parser (symbols)</title>
<link rel="stylesheet" href="../../../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../../index.html" title="Spirit 2.5.8">
<link rel="up" href="../string.html" title="String Parsers">
<link rel="prev" href="string.html" title="String Parsers (string, lit)">
<link rel="next" href="../../s04.html" title="Qi Index">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="string.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../string.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../../s04.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="spirit.qi.reference.string.symbols"></a><a class="link" href="symbols.html" title="Symbols Parser (symbols)">Symbols Parser
          (<code class="computeroutput"><span class="identifier">symbols</span></code>)</a>
</h5></div></div></div>
<h6>
<a name="spirit.qi.reference.string.symbols.h0"></a>
            <span class="phrase"><a name="spirit.qi.reference.string.symbols.description"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.description">Description</a>
          </h6>
<p>
            The class <code class="computeroutput"><span class="identifier">symbols</span></code> implements
            a symbol table: an associative container (or map) of key-value pairs
            where the keys are strings. The <code class="computeroutput"><span class="identifier">symbols</span></code>
            class can work efficiently with 8, 16, 32 and even 64 bit characters.
          </p>
<p>
            Traditionally, symbol table management is maintained separately outside
            the grammar through semantic actions. Contrary to standard practice,
            the Spirit symbol table class <code class="computeroutput"><span class="identifier">symbols</span></code>
            is-a parser, an instance of which may be used anywhere in the grammar
            specification. It is an example of a dynamic parser. A dynamic parser
            is characterized by its ability to modify its behavior at run time. Initially,
            an empty symbols object matches nothing. At any time, symbols may be
            added, thus, dynamically altering its behavior.
          </p>
<h6>
<a name="spirit.qi.reference.string.symbols.h1"></a>
            <span class="phrase"><a name="spirit.qi.reference.string.symbols.header"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.header">Header</a>
          </h6>
<pre class="programlisting"><span class="comment">// forwards to &lt;boost/spirit/home/qi/string/symbols.hpp&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">qi_symbols</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
</pre>
<p>
            Also, see <a class="link" href="../../../structure/include.html" title="Include">Include Structure</a>.
          </p>
<h6>
<a name="spirit.qi.reference.string.symbols.h2"></a>
            <span class="phrase"><a name="spirit.qi.reference.string.symbols.namespace"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.namespace">Namespace</a>
          </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                    <p>
                      Name
                    </p>
                  </th></tr></thead>
<tbody>
<tr><td>
                    <p>
                      <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">qi</span><span class="special">::</span><span class="identifier">symbols</span></code>
                    </p>
                  </td></tr>
<tr><td>
                    <p>
                      <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">qi</span><span class="special">::</span><span class="identifier">tst</span></code>
                    </p>
                  </td></tr>
<tr><td>
                    <p>
                      <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">qi</span><span class="special">::</span><span class="identifier">tst_map</span></code>
                    </p>
                  </td></tr>
</tbody>
</table></div>
<h6>
<a name="spirit.qi.reference.string.symbols.h3"></a>
            <span class="phrase"><a name="spirit.qi.reference.string.symbols.synopsis"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.synopsis">Synopsis</a>
          </h6>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Char</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Lookup</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">symbols</span><span class="special">;</span>
</pre>
<h6>
<a name="spirit.qi.reference.string.symbols.h4"></a>
            <span class="phrase"><a name="spirit.qi.reference.string.symbols.template_parameters"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.template_parameters">Template
            parameters</a>
          </h6>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                    <p>
                      Parameter
                    </p>
                  </th>
<th>
                    <p>
                      Description
                    </p>
                  </th>
<th>
                    <p>
                      Default
                    </p>
                  </th>
</tr></thead>
<tbody>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">Char</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      The character type of the symbol strings.
                    </p>
                  </td>
<td>
                    <p>
                      <code class="computeroutput"><span class="keyword">char</span></code>
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">T</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      The data type associated with each symbol.
                    </p>
                  </td>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">unused_type</span></code>
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">Lookup</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      The symbol search implementation
                    </p>
                  </td>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">tst</span><span class="special">&lt;</span><span class="identifier">Char</span><span class="special">,</span>
                      <span class="identifier">T</span><span class="special">&gt;</span></code>
                    </p>
                  </td>
</tr>
</tbody>
</table></div>
<h6>
<a name="spirit.qi.reference.string.symbols.h5"></a>
            <span class="phrase"><a name="spirit.qi.reference.string.symbols.model_of"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.model_of">Model
            of</a>
          </h6>
<div class="blockquote"><blockquote class="blockquote"><p>
              <a class="link" href="../parser_concepts/primitiveparser.html" title="PrimitiveParser"><code class="computeroutput"><span class="identifier">PrimitiveParser</span></code></a>
            </p></blockquote></div>
<div class="variablelist">
<p class="title"><b>Notation</b></p>
<dl class="variablelist">
<dt><span class="term"><code class="computeroutput"><span class="identifier">Sym</span></code></span></dt>
<dd><p>
                  A <code class="computeroutput"><span class="identifier">symbols</span></code> type.
                </p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">Char</span></code></span></dt>
<dd><p>
                  A character type.
                </p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">T</span></code></span></dt>
<dd><p>
                  A data type.
                </p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">sym</span></code>, <code class="computeroutput"><span class="identifier">sym2</span></code></span></dt>
<dd><p>
                  <code class="computeroutput"><span class="identifier">symbols</span></code> objects.
                </p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">sseq</span></code></span></dt>
<dd><p>
                  An <a href="https://en.wikipedia.org/wiki/Standard_Template_Library" target="_top">STL</a>
                  container of strings.
                </p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">dseq</span></code></span></dt>
<dd><p>
                  An <a href="https://en.wikipedia.org/wiki/Standard_Template_Library" target="_top">STL</a>
                  container of data with <code class="computeroutput"><span class="identifier">value_type</span></code>
                  <code class="computeroutput"><span class="identifier">T</span></code>.
                </p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">s1</span></code>...<code class="computeroutput"><span class="identifier">sN</span></code></span></dt>
<dd><p>
                  A <a class="link" href="../basics.html#spirit.qi.reference.basics.string">String</a>.
                </p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">d1</span></code>...<code class="computeroutput"><span class="identifier">dN</span></code></span></dt>
<dd><p>
                  Objects of type <code class="computeroutput"><span class="identifier">T</span></code>.
                </p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">f</span></code></span></dt>
<dd><p>
                  A callable function or function object.
                </p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">f</span></code>, <code class="computeroutput"><span class="identifier">l</span></code></span></dt>
<dd><p>
                  <code class="computeroutput"><span class="identifier">ForwardIterator</span></code>
                  first/last pair.
                </p></dd>
</dl>
</div>
<h6>
<a name="spirit.qi.reference.string.symbols.h6"></a>
            <span class="phrase"><a name="spirit.qi.reference.string.symbols.expression_semantics"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.expression_semantics">Expression
            Semantics</a>
          </h6>
<p>
            Semantics of an expression is defined only where it differs from, or
            is not defined in <a class="link" href="../parser_concepts/primitiveparser.html" title="PrimitiveParser"><code class="computeroutput"><span class="identifier">PrimitiveParser</span></code></a>.
          </p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                    <p>
                      Expression
                    </p>
                  </th>
<th>
                    <p>
                      Semantics
                    </p>
                  </th>
</tr></thead>
<tbody>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">Sym</span><span class="special">()</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Construct an empty symbols names <code class="computeroutput"><span class="string">"symbols"</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">Sym</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Construct an empty symbols named <code class="computeroutput"><span class="identifier">name</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">Sym</span><span class="special">(</span><span class="identifier">sym2</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Copy construct a symbols from <code class="computeroutput"><span class="identifier">sym2</span></code>
                      (Another <code class="computeroutput"><span class="identifier">symbols</span></code>
                      object).
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">Sym</span><span class="special">(</span><span class="identifier">sseq</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Construct symbols from <code class="computeroutput"><span class="identifier">sseq</span></code>
                      (an <a href="https://en.wikipedia.org/wiki/Standard_Template_Library" target="_top">STL</a>
                      container of strings) named <code class="computeroutput"><span class="string">"symbols"</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">Sym</span><span class="special">(</span><span class="identifier">sseq</span><span class="special">,</span>
                      <span class="identifier">name</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Construct symbols from <code class="computeroutput"><span class="identifier">sseq</span></code>
                      (an <a href="https://en.wikipedia.org/wiki/Standard_Template_Library" target="_top">STL</a>
                      container of strings) named <code class="computeroutput"><span class="identifier">name</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">Sym</span><span class="special">(</span><span class="identifier">sseq</span><span class="special">,</span>
                      <span class="identifier">dseq</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Construct symbols from <code class="computeroutput"><span class="identifier">sseq</span></code>
                      and <code class="computeroutput"><span class="identifier">dseq</span></code> (An
                      <a href="https://en.wikipedia.org/wiki/Standard_Template_Library" target="_top">STL</a>
                      container of strings and an <a href="https://en.wikipedia.org/wiki/Standard_Template_Library" target="_top">STL</a>
                      container of data with <code class="computeroutput"><span class="identifier">value_type</span></code>
                      <code class="computeroutput"><span class="identifier">T</span></code>) which is
                      named <code class="computeroutput"><span class="string">"symbols"</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">Sym</span><span class="special">(</span><span class="identifier">sseq</span><span class="special">,</span>
                      <span class="identifier">dseq</span><span class="special">,</span>
                      <span class="identifier">name</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Construct symbols from <code class="computeroutput"><span class="identifier">sseq</span></code>
                      and <code class="computeroutput"><span class="identifier">dseq</span></code> (An
                      <a href="https://en.wikipedia.org/wiki/Standard_Template_Library" target="_top">STL</a>
                      container of strings and an <a href="https://en.wikipedia.org/wiki/Standard_Template_Library" target="_top">STL</a>
                      container of data with <code class="computeroutput"><span class="identifier">value_type</span></code>
                      <code class="computeroutput"><span class="identifier">T</span></code>) which is
                      named <code class="computeroutput"><span class="identifier">name</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">sym</span> <span class="special">=</span>
                      <span class="identifier">sym2</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Assign <code class="computeroutput"><span class="identifier">sym2</span></code>
                      to <code class="computeroutput"><span class="identifier">sym</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">sym</span> <span class="special">=</span>
                      <span class="identifier">s1</span><span class="special">,</span>
                      <span class="identifier">s2</span><span class="special">,</span>
                      <span class="special">...,</span> <span class="identifier">sN</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Assign one or more symbols (<code class="computeroutput"><span class="identifier">s1</span></code>...<code class="computeroutput"><span class="identifier">sN</span></code>) to <code class="computeroutput"><span class="identifier">sym</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">sym</span> <span class="special">+=</span>
                      <span class="identifier">s1</span><span class="special">,</span>
                      <span class="identifier">s2</span><span class="special">,</span>
                      <span class="special">...,</span> <span class="identifier">sN</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Add one or more symbols (<code class="computeroutput"><span class="identifier">s1</span></code>...<code class="computeroutput"><span class="identifier">sN</span></code>) to <code class="computeroutput"><span class="identifier">sym</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">add</span><span class="special">(</span><span class="identifier">s1</span><span class="special">)(</span><span class="identifier">s2</span><span class="special">)...(</span><span class="identifier">sN</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Add one or more symbols (<code class="computeroutput"><span class="identifier">s1</span></code>...<code class="computeroutput"><span class="identifier">sN</span></code>) to <code class="computeroutput"><span class="identifier">sym</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">add</span><span class="special">(</span><span class="identifier">s1</span><span class="special">,</span>
                      <span class="identifier">d1</span><span class="special">)(</span><span class="identifier">s2</span><span class="special">,</span>
                      <span class="identifier">d2</span><span class="special">)...(</span><span class="identifier">sN</span><span class="special">,</span>
                      <span class="identifier">dN</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Add one or more symbols (<code class="computeroutput"><span class="identifier">s1</span></code>...<code class="computeroutput"><span class="identifier">sN</span></code>) with associated data
                      (<code class="computeroutput"><span class="identifier">d1</span></code>...<code class="computeroutput"><span class="identifier">dN</span></code>) to <code class="computeroutput"><span class="identifier">sym</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">sym</span> <span class="special">-=</span>
                      <span class="identifier">s1</span><span class="special">,</span>
                      <span class="identifier">s2</span><span class="special">,</span>
                      <span class="special">...,</span> <span class="identifier">sN</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Remove one or more symbols (<code class="computeroutput"><span class="identifier">s1</span></code>...<code class="computeroutput"><span class="identifier">sN</span></code>) from <code class="computeroutput"><span class="identifier">sym</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">remove</span><span class="special">(</span><span class="identifier">s1</span><span class="special">)(</span><span class="identifier">s2</span><span class="special">)...(</span><span class="identifier">sN</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Remove one or more symbols (<code class="computeroutput"><span class="identifier">s1</span></code>...<code class="computeroutput"><span class="identifier">sN</span></code>) from <code class="computeroutput"><span class="identifier">sym</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">clear</span><span class="special">()</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Erase all of the symbols in <code class="computeroutput"><span class="identifier">sym</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="identifier">s</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Return a reference to the object associated with symbol, <code class="computeroutput"><span class="identifier">s</span></code>. If <code class="computeroutput"><span class="identifier">sym</span></code>
                      does not already contain such an object, <code class="computeroutput"><span class="identifier">at</span></code>
                      inserts the default object <code class="computeroutput"><span class="identifier">T</span><span class="special">()</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">find</span><span class="special">(</span><span class="identifier">s</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Return a pointer to the object associated with symbol, <code class="computeroutput"><span class="identifier">s</span></code>. If <code class="computeroutput"><span class="identifier">sym</span></code>
                      does not already contain such an object, <code class="computeroutput"><span class="identifier">find</span></code>
                      returns a null pointer.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">prefix_find</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span>
                      <span class="identifier">l</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Return a pointer to the object associated with longest symbol
                      that matches the beginning of the range <code class="computeroutput"><span class="special">[</span><span class="identifier">f</span><span class="special">,</span>
                      <span class="identifier">l</span><span class="special">)</span></code>,
                      and updates <code class="computeroutput"><span class="identifier">f</span></code>
                      to point to one past the end of that match. If no symbol matches,
                      then return a null pointer, and <code class="computeroutput"><span class="identifier">f</span></code>
                      is unchanged.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">f</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      For each symbol in <code class="computeroutput"><span class="identifier">sym</span></code>,
                      <code class="computeroutput"><span class="identifier">s</span></code>, a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_string</span><span class="special">&lt;</span><span class="identifier">Char</span><span class="special">&gt;</span></code>
                      with associated data, <code class="computeroutput"><span class="identifier">d</span></code>,
                      an object of type <code class="computeroutput"><span class="identifier">T</span></code>,
                      invoke <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span>
                      <span class="identifier">d</span><span class="special">)</span></code>
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Retrieve the current name of the symbols object.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">name</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Set the current name of the symbols object to be <code class="computeroutput"><span class="identifier">name</span></code>.
                    </p>
                  </td>
</tr>
</tbody>
</table></div>
<h6>
<a name="spirit.qi.reference.string.symbols.h7"></a>
            <span class="phrase"><a name="spirit.qi.reference.string.symbols.attributes"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.attributes">Attributes</a>
          </h6>
<p>
            The attribute of <code class="computeroutput"><span class="identifier">symbol</span><span class="special">&lt;</span><span class="identifier">Char</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span></code> is <code class="computeroutput"><span class="identifier">T</span></code>.
          </p>
<h6>
<a name="spirit.qi.reference.string.symbols.h8"></a>
            <span class="phrase"><a name="spirit.qi.reference.string.symbols.complexity"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.complexity">Complexity</a>
          </h6>
<p>
            The default implementation uses a Ternary Search Tree (TST) with complexity:
          </p>
<div class="blockquote"><blockquote class="blockquote"><p>
              O(log n+k)
            </p></blockquote></div>
<p>
            Where k is the length of the string to be searched in a TST with n strings.
          </p>
<p>
            TSTs are faster than hashing for many typical search problems especially
            when the search interface is iterator based. TSTs are many times faster
            than hash tables for unsuccessful searches since mismatches are discovered
            earlier after examining only a few characters. Hash tables always examine
            an entire key when searching.
          </p>
<p>
            An alternative implementation uses a hybrid hash-map front end (for the
            first character) plus a TST: <code class="computeroutput"><span class="identifier">tst_map</span></code>.
            This gives us a complexity of
          </p>
<div class="blockquote"><blockquote class="blockquote"><p>
              O(1 + log n+k-1)
            </p></blockquote></div>
<p>
            This is found to be significantly faster than plain TST, albeit with
            a bit more memory usage requirements (each slot in the hash-map is a
            TST node). If you require a lot of symbols to be searched, use the <code class="computeroutput"><span class="identifier">tst_map</span></code> implementation. This can be
            done by using <code class="computeroutput"><span class="identifier">tst_map</span></code>
            as the third template parameter to the symbols class:
          </p>
<pre class="programlisting"><span class="identifier">symbols</span><span class="special">&lt;</span><span class="identifier">Char</span><span class="special">,</span> <span class="identifier">T</span><span class="special">,</span> <span class="identifier">tst_map</span><span class="special">&lt;</span><span class="identifier">Char</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">sym</span><span class="special">;</span>
</pre>
<h6>
<a name="spirit.qi.reference.string.symbols.h9"></a>
            <span class="phrase"><a name="spirit.qi.reference.string.symbols.example"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.example">Example</a>
          </h6>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
              The test harness for the example(s) below is presented in the <a class="link" href="../basics.html#spirit.qi.reference.basics.examples">Basics Examples</a>
              section.
            </p></td></tr>
</table></div>
<p>
            Some using declarations:
          </p>
<p>
</p>
<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">qi</span><span class="special">::</span><span class="identifier">symbols</span><span class="special">;</span>
</pre>
<p>
          </p>
<p>
            Symbols with data:
          </p>
<p>
</p>
<pre class="programlisting"><span class="identifier">symbols</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">,</span> <span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">sym</span><span class="special">;</span>

<span class="identifier">sym</span><span class="special">.</span><span class="identifier">add</span>
    <span class="special">(</span><span class="string">"Apple"</span><span class="special">,</span> <span class="number">1</span><span class="special">)</span>
    <span class="special">(</span><span class="string">"Banana"</span><span class="special">,</span> <span class="number">2</span><span class="special">)</span>
    <span class="special">(</span><span class="string">"Orange"</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span>
<span class="special">;</span>

<span class="keyword">int</span> <span class="identifier">i</span><span class="special">;</span>
<span class="identifier">test_parser_attr</span><span class="special">(</span><span class="string">"Banana"</span><span class="special">,</span> <span class="identifier">sym</span><span class="special">,</span> <span class="identifier">i</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
</pre>
<p>
          </p>
<p>
            When <code class="computeroutput"><span class="identifier">symbols</span></code> is used
            for case-insensitive parsing (in a <a class="link" href="../directive/no_case.html" title="Parser Directive Inhibiting Case Sensitivity (no_case[])"><code class="computeroutput"><span class="identifier">no_case</span></code></a> directive), added symbol
            strings should be in lowercase. Symbol strings containing one or more
            uppercase characters will not match any input when symbols is used in
            a <code class="computeroutput"><span class="identifier">no_case</span></code> directive.
          </p>
<p>
</p>
<pre class="programlisting"><span class="identifier">symbols</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">,</span> <span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">sym</span><span class="special">;</span>

<span class="identifier">sym</span><span class="special">.</span><span class="identifier">add</span>
    <span class="special">(</span><span class="string">"apple"</span><span class="special">,</span> <span class="number">1</span><span class="special">)</span>    <span class="comment">// symbol strings are added in lowercase...</span>
    <span class="special">(</span><span class="string">"banana"</span><span class="special">,</span> <span class="number">2</span><span class="special">)</span>
    <span class="special">(</span><span class="string">"orange"</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span>
<span class="special">;</span>

<span class="keyword">int</span> <span class="identifier">i</span><span class="special">;</span>
<span class="comment">// ...because sym is used for case-insensitive parsing</span>
<span class="identifier">test_parser_attr</span><span class="special">(</span><span class="string">"Apple"</span><span class="special">,</span> <span class="identifier">no_case</span><span class="special">[</span> <span class="identifier">sym</span> <span class="special">],</span> <span class="identifier">i</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="identifier">test_parser_attr</span><span class="special">(</span><span class="string">"ORANGE"</span><span class="special">,</span> <span class="identifier">no_case</span><span class="special">[</span> <span class="identifier">sym</span> <span class="special">],</span> <span class="identifier">i</span><span class="special">);</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
</pre>
<p>
          </p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2001-2011 Joel de Guzman, Hartmut Kaiser<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="string.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../string.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../../s04.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
